Timeout Policies

BindAI supports a basic workflow timeout policy through the workflow executor. The current implementation checks elapsed workflow time before starting each node. If the configured timeout has been exceeded at that check, the executor fails the workflow. This is a cooperative timeout check, not a hard execution deadline. It does not interrupt a node that is already running, and the fail_workflow configuration field is not currently used.

Current Behavior

The workflow runtime provides a TimeoutPolicy configuration:

from bindai_workflow.timeout import TimeoutPolicy

policy = TimeoutPolicy(
    seconds=30,
)

The policy defines a maximum workflow duration in seconds. During execution, the executor compares elapsed time with the configured limit before starting a node. If the limit has been exceeded, it returns a workflow failure with the error message:

Workflow timeout.

The timeout is therefore detected at an execution check, rather than by a separate timer that interrupts running work.

What Is Implemented

The current timeout implementation provides:

A TimeoutPolicy configuration class
A configurable timeout duration through seconds
An elapsed-time check in the workflow executor
Workflow failure when the timeout is exceeded at the check

The following capabilities are not currently provided by this implementation:

Interrupting a node that is already running
Guaranteed termination at the exact timeout boundary
Automatic cancellation of an in-progress external operation
A timeout-specific retry mechanism
An independently running timeout monitor

The fail_workflow field exists on TimeoutPolicy, but the executor does not currently use it to select different behavior. Applications should not treat the timeout as a hard guarantee that all work will stop within the configured number of seconds.

Timeout Configuration

A timeout policy can be constructed as follows:

from bindai_workflow.timeout import TimeoutPolicy

timeout_policy = TimeoutPolicy(
    seconds=30,
    fail_workflow=True,
)

The current fields are:

Field	Required	Default	Current behavior
`seconds`	Yes	No default	Used by the executor to check elapsed workflow time
`fail_workflow`	No	`True`	Defined but not used by the executor

The seconds field controls the timeout threshold used by the executor. The fail_workflow field does not currently change timeout handling. The policy class defines these values, but the workflow execution context must be configured with the policy for the executor to apply it.

How the Timeout Check Works

The executor checks elapsed time before starting a workflow node. Conceptually:

Workflow Execution
        |
        v
Check Elapsed Time
        |
        v
Limit Exceeded?
    /       \
  No         Yes
  |           |
  v           v
Start Node  Workflow Failure
  |
  v
Execute Node

If the timeout has not been exceeded at the check, execution proceeds to the node. If the timeout has been exceeded, the executor returns a failure with the message Workflow timeout. Because the check occurs between node executions, the executor may not detect an exceeded timeout until the next check.

Timeout Is Not Hard Cancellation

The current timeout mechanism does not interrupt a node that is already running. For example, consider a node that makes a slow external request:

Start Workflow
      |
      v
Check Timeout
      |
      v
Start External Request
      |
      v
Request Still Running
      |
      v
Request Returns
      |
      v
Next Timeout Check

If the timeout expires while the external request is running, the executor does not automatically terminate that request at the timeout boundary. The timeout can be detected when execution reaches the next check. If the node fails or blocks indefinitely and execution never reaches another check, the workflow-level timeout mechanism does not independently interrupt it. For operations that require strict time limits, use appropriate timeout or cancellation controls in the underlying tool, client, or external service where available.

Timeout vs Loop

BindAI supports workflow loops, but a timeout policy is not a substitute for an explicit loop termination condition. A loop might look like this:

Loop
  |
  v
Process
  |
  v
Update State
  |
  +----> Loop

The workflow logic should define when the loop exits. The timeout policy can detect that the workflow has exceeded its time limit at an executor check, but it should not be treated as a hard safety boundary for an unbounded loop or a guarantee that a running node will be interrupted. Use explicit termination conditions and ensure that potentially long-running operations have appropriate controls.

Timeout vs Retry

Timeout and retry policies address different execution concerns.

Timeout checks elapsed workflow time during execution.
Retry handles exceptions raised during node execution when a retry policy is configured.

The two mechanisms should not be assumed to provide a strict combined execution deadline. For example:

Workflow
   |
   v
Timeout Check
   |
   v
Execute Node
   |
   +---- Exception ----> Retry
   |                       |
   |                       v
   |                  Execute Node
   |
   +---- Success --------> Continue

The current retry implementation retries immediately. The timeout check occurs before node execution, so repeated attempts can continue within the node execution loop before the executor reaches its next timeout check. Neither mechanism guarantees that an already-running node will be interrupted.

External Operations

BindAI supports external operations through tools and connection-backed integrations. For example:

Workflow
   |
   v
Webhook Tool
   |
   v
External Service

The workflow timeout policy does not automatically impose an interruptible timeout on the external service or its network request. External operation timeout behavior depends on the tool, client library, and integration being used. Where supported, configure operation-level timeouts as well as any workflow-level timeout policy. This is especially important for network requests, AI provider calls, database operations, and other integrations that may block or take a long time to respond.

Long-Running Workflows

A workflow may contain operations that take a significant amount of time. The current timeout policy provides a way to detect excessive elapsed workflow time at executor checks, but it does not guarantee termination at the configured duration. For example, a policy configured with:

TimeoutPolicy(seconds=30)

does not guarantee that all workflow activity stops within 30 seconds. A node that starts before the threshold is exceeded may continue running past that threshold. Applications should account for the behavior of long-running nodes and configure operation-level safeguards where appropriate.

Current BindAI V1 Scope

The current workflow runtime includes a basic timeout policy, with important limitations. The implementation provides elapsed-time checking and workflow failure when a timeout is detected. It does not provide hard interruption of running nodes, guaranteed termination at the configured boundary, or use of the fail_workflow field. Other workflow capabilities, such as conditions, loops, parallel execution, join synchronization, and human tasks, are separate from the timeout mechanism.

Documentation Scope

This page documents the timeout behavior currently implemented and verified in the workflow runtime. It does not promise:

Hard cancellation of running nodes
Immediate termination when the timeout expires
Automatic cancellation of external operations
Different failure behavior based on fail_workflow

These capabilities should be documented as supported features only after their runtime behavior is implemented and verified.

Summary

BindAI provides a basic workflow timeout policy through TimeoutPolicy. The executor checks elapsed time before starting each node and returns a workflow failure if the configured limit has been exceeded at that check. The timeout is not a hard execution deadline: a node that is already running is not interrupted, and the fail_workflow field is currently unused. Use this feature to detect excessive workflow duration, but do not rely on it as a substitute for operation-level timeouts or hard cancellation.

Getting Started

Core

Tools

Memory

Knowledge

Workflows

Projects

Templates

Connections

API Reference

Automation

Roadmap

06.8 timeout

Timeout Policies

Current Behavior

What Is Implemented

Timeout Configuration

How the Timeout Check Works

Timeout Is Not Hard Cancellation

Timeout vs Loop

Timeout vs Retry

External Operations

Long-Running Workflows

Current BindAI V1 Scope

Documentation Scope

Summary

​Timeout Policies

​Current Behavior

​What Is Implemented

​Timeout Configuration

​How the Timeout Check Works

​Timeout Is Not Hard Cancellation

​Timeout vs Loop

​Timeout vs Retry

​External Operations

​Long-Running Workflows

​Current BindAI V1 Scope

​Documentation Scope

​Summary

Timeout Policies

Current Behavior

What Is Implemented

Timeout Configuration

How the Timeout Check Works

Timeout Is Not Hard Cancellation

Timeout vs Loop

Timeout vs Retry

External Operations

Long-Running Workflows

Current BindAI V1 Scope

Documentation Scope

Summary